/* vim: set sw=8 ts=8 sts=8 expandtab: */
#ifndef CMAID_MAP_H
#define CMAID_MAP_H

/**
 * @defgroup Cmaid_Map The Map Class
 * @ingroup Classes
 * @brief A map to associate a key with a value
 *
 * The map class provides an interface to associate a key object with a value
 * object. This is also known as associative array. The key needs to be
 * unique, else you would get collisions, but the values maybe the same for
 * two different keys.
 *
 * The iterators attached with cmaid_container_iter_attach() function,
 * iterate over the key values. To iterate over the values use the map
 * function cmaid_map_value_iter_attach().
 *
 */
/**
 * @brief Type definition of the Map Class
 * @ingroup Cmaid_Map
 */
typedef Cmaid_Container Cmaid_Map;
/**
 * @defgroup Cmaid_Map_Interface The Map Interface
 * @ingroup Cmaid_Map
 *
 * You only have to deal with the interface structure directly, if you are
 * going to write an implementation of the interface. Else you can safely
 * ignore this.
 *
 * @{
 */
/** Type definition for the @em set callback */
typedef void *(*Cmaid_Map_Set_Cb)(Cmaid_Map *m, const void *key,
                                        const void *data);
/** Type definition for the @em remove callback */
typedef void  (*Cmaid_Map_Remove_Cb)(Cmaid_Map *m, const void *key);
/** Type definition for the @em get callback */
typedef void *(*Cmaid_Map_Get_Cb)(Cmaid_Map *m, const void *key);
/** Type definition for the @em attach @em iterator callback */
typedef void  (*Cmaid_Map_Value_Iter_Attach_Cb)(Cmaid_Map *m, Cmaid_Iter *it);

/** Type definition for the @em map interface */
typedef struct Cmaid_Map_Interface Cmaid_Map_Interface;

/**
 * @brief The Map Interface structure
 * The map interface is inheriting from the container and thus must also
 * have interface functions for the container.
 */
struct Cmaid_Map_Interface
{
        Cmaid_Container_Interface      container_if; 
        Cmaid_Map_Set_Cb               set;
        Cmaid_Map_Remove_Cb            remove;
        Cmaid_Map_Get_Cb               get;
        Cmaid_Map_Value_Iter_Attach_Cb value_iter_attach;
};
/**
 * @}
 */

/**
 * @addtogroup Cmaid_Map
 * @{
 */
CMAID_INLINE void      *cmaid_map_set(Cmaid_Map *m, const void *key,
                                                        const void *data);
CMAID_INLINE void       cmaid_map_remove(Cmaid_Map *m, const void *key);
CMAID_INLINE void      *cmaid_map_get(Cmaid_Map *m, const void *key);
CMAID_INLINE void       cmaid_map_value_iter_attach(Cmaid_Map *m,
                                                        Cmaid_Iter *iter);
/**
 * @}
 */
#include <cmaid_map_funcdef.h>

#endif
